---
description: Компонент-обертка над Spinner.
---

<Overview group="feedback">
# ScreenSpinner [tag:component]

Компонент-обертка над [`Spinner`](/components/spinner). Используется в случаях, когда требуется заблокировать весь интерфейс до завершения асинхронного процесса.

</Overview>

<Playground>

```jsx
const [spinner, setSpinner] = React.useState(null);

const showSpinner = () => {
  setSpinner(<ScreenSpinner state="cancelable" mode="overlay" onClick={() => setSpinner(null)} />);
};

return (
  <>
    <Button onClick={showSpinner}>Показать индикатор</Button>
    {spinner}
  </>
);
```

</Playground>

## Подкомпоненты

Для возможности собрать компонент по частям доступны подкомпоненты. Это позволит более гибко влиять на эти части, а также
отвязаться от логики порталов и всплывающих окон (например, при появлении компонента блокируется скролл).

<Playground>
  ```jsx
  <ScreenSpinner.Container>
    <ScreenSpinner.Loader />
    <ScreenSpinner.SwapIcon />
  </ScreenSpinner.Container>
  ```
</Playground>

### ScreenSpinner.Container

Подкомпонент контейнера, которой содержит все части `ScreenSpinner`.

### ScreenSpinner.Loader

Подкомпонент спиннера.

### ScreenSpinner.SwapIcon

Подкомпонент для иконок.

## Внешний вид

Задаётся свойством `mode`.

Помимо стандартного стиля компонента (`mode="shadow"`), есть возможность задать `mode="overlay"`,
для использования индикатора загрузки поверх цветных элементов или фотографий.

<Playground>
  ```jsx
  <ScreenSpinner.Container mode="overlay">
    <ScreenSpinner.Loader />
    <ScreenSpinner.SwapIcon />
  </ScreenSpinner.Container>
  ```
</Playground>

## Состояния

Задаётся свойством `state`.

- `"loading"` — состояние исполняющегося процесса (по умолчанию);
- `"cancelable"` — состояние исполняющегося процесса с возможностью отмены;
- `"done"` — успешное завершение процесса;
- `"error"` — завершение процесса с ошибкой;
- `"custom"` — пользовательский вариант состояния процесса.

Состояние отвечает за иконку, которая будет отрисована. Если вам не подходит ни одно из представленных состояний,
то используйте `state="custom"`. Задать пользовательскую иконку в таком случае можно через свойство [`customIcon`](#custom-icon).

<Playground>
  ```jsx
  <ScreenSpinner.Container>
    <ScreenSpinner.Loader />
    <ScreenSpinner.SwapIcon />
  </ScreenSpinner.Container>
  <ScreenSpinner.Container state="cancelable">
    <ScreenSpinner.Loader />
    <ScreenSpinner.SwapIcon />
  </ScreenSpinner.Container>
  <ScreenSpinner.Container state="done">
    <ScreenSpinner.Loader />
    <ScreenSpinner.SwapIcon />
  </ScreenSpinner.Container>
  <ScreenSpinner.Container state="error">
    <ScreenSpinner.Loader />
    <ScreenSpinner.SwapIcon />
  </ScreenSpinner.Container>
  <ScreenSpinner.Container state="custom" customIcon={<Icon56CheckCircleOutline />}>
    <ScreenSpinner.Loader />
    <ScreenSpinner.SwapIcon />
  </ScreenSpinner.Container>
  ```
</Playground>

## Сопроводительный текст

Задаётся свойством `label`. Текст располагается под иконкой. Если вы хотите использовать просто иконку
без поясняющего текста, пожалуйста, не забывайте передавать описание иконки для ассистивных технологий через свойство `children`.

## Пользовательские иконки [#custom-icon]

Задаётся свойством `customIcon` и работает совместно со `state="custom"`, .

```jsx
import { ScreenSpinner } from '@vkontakte/vkui';
import { Icon56CheckCircleOutline } from '@vkontakte/icons';

<ScreenSpinner state="custom" customIcon={<Icon56CheckCircleOutline />} />;
```

## Управление порталами

VKUI использует [порталы](https://react.dev/reference/react-dom/createPortal) для рендеринга `ScreenSpinner`.

Свойство `usePortal` позволяет настраивать порталы:

- `true` — использует свойство `portalRoot`, указанное в компоненте `AppRoot`, если не указано, то `document.body` (по умолчанию);
- `false`/`null` — отключает рендер компонента в отдельном контейнере, он будет рендериться непосредственно по месту определения;

Также можно указать конкретный `DOM`-элемент (полученный, например, через `document.getElementById`)
или ссылку на `DOM`-элемент ([`ref`-объект](https://react.dev/learn/manipulating-the-dom-with-refs)).

## Доступность (a11y) [#a11y]

Чтобы уведомить пользователей скринридеров о выполнении асинхронного процесса,
проставьте на `SplitLayout` или любом корневом компоненте, в котором выполняется процесс,
метки [`aria-busy`](https://doka.guide/a11y/aria-busy/) и [`aria-live`](https://doka.guide/a11y/aria-live/).

Чтобы заменить текст, который прочитает скринридер, передайте его в `children`.
Он будет скрыт визуально, но останется доступным для ассистивных технологий.
Если вы используете свойство `label`, то передавать `children` не нужно, будет зачитан текст, переданный в `label`.

Свойство `cancelLabel` используется при `state="cancelable"` и делает кнопку отмены доступной для ассистивных технологий.

### disableAnimation

Компонент поддерживает свойство `disableAnimation`, которое позволяет отключить анимацию у спиннера.

## Свойства и методы [#api]

<PropsTable name="ScreenSpinner">
### ScreenSpinner [#screen-spinner-api]

### ScreenSpinner.Container [#screen-spinner-container-api]

### ScreenSpinner.Loader [#screen-spinner-loader-api]

### ScreenSpinner.SwapIcon [#screen-spinner-swap-icon-api]

</PropsTable>
